home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / programming / c / awin / awin.doc < prev    next >
Encoding:
Text File  |  1999-05-17  |  28.0 KB  |  1,065 lines
  1. TABLE OF CONTENTS
  2.  
  3. awin.o/--introduction--
  4. awin.o/awcreatedisplay
  5. awin.o/awdeletedisplay
  6. awin.o/awsetdebuglevel
  7. awin.o/awreadargs
  8. awin.o/awfreeargs
  9. awin.o/awcreatetimer
  10. awin.o/awrestarttimer
  11. awin.o/awreadtimer
  12. awin.o/awreadtimer_us
  13. awin.o/awdeletetimer
  14. awin.o/awsetidcmphook
  15. awin.o/awsetidcmpflags
  16. awin.o/awinitchunkystruct
  17. awin.o/awallocchunky
  18. awin.o/awfreechunky
  19. awin.o/awopendisplay
  20. awin.o/awclosedisplay
  21. awin.o/awsetpalette
  22. awin.o/awhandleinput
  23. awin.o/awrenderchunky
  24. awin.o/awrenderchunky_show
  25. awin.o/awloadfile
  26. awin.o/awfreefile
  27. awin.o/--introduction--                                awin.o/--introduction--
  28.  
  29.    DESCRIPTION
  30.     - easy-to-use API for RTG chunky display
  31.     - 0x0 compiles with GeekGadgets egcs and PhxAss (both free) AND
  32.       SAS/C 6.5x and PhxAss
  33.     - PowerUP version compiles with GG egcs + SAS/C PPC
  34.     - possible to use GenAm (DevPac) or basm instead of PhxAss
  35.  
  36.    REQUIREMENTS
  37.     - runtime M68K:
  38.       o MC68020 or better
  39.       o Kickstart 3.0 or better
  40.     - runtime PPC, add:
  41.       o PowerPC 603e or better
  42.       o ppc.library V46.6 or better
  43.     - compiling:
  44.       o dev/misc/CGraphX-DevKit.lha properly installed
  45.       o latest xpk devkit includes properly installed
  46.       o cgxvideo.h installed (from cgfx4 devkit for example)
  47.       o GeekGadgets egcs or SAS/C 6.5x
  48.       o dev/asm/PhxAss439.lha or DevPac GenAm properly installed
  49.       o egcs PPC: patched OS includes in gg:ppc-amigaos/os-include/
  50.         (ixemul ppc bridge has script for this, geninclude.pl)
  51.         and SAS/C PPC lib:. also libmoto.a is linked in by default so
  52.         if you'd better have that too.
  53.       o SAS/C PPC: vbcc vlink or GG ppc-amigaos-ld. also libmoto.a is
  54.         linked in by default so if you'd better have that.
  55.  
  56.    MOTIVATION
  57.     I got really tired of demos not supporting gfxcards, and
  58.     lazy coders not supporting all systems when it indeed is
  59.     possible. Either products hit hardware directly or require
  60.     gfxcard. One word is enough to describe this situation:
  61.     `sucks'. RTGMaster is quite nice, but has its (known)
  62.     problems, awin should be better in many ways.
  63.  
  64.    PURPOSE
  65.     awin is a extremely easy to use and yet powerful RTG system
  66.     for 8 and 16 bit chunky displays. It is mainly intended for
  67.     intro/demo/game coders who'd like to have good chunky display
  68.     support in their products.
  69.  
  70.    FEATURES
  71.     - compiles for M68K and PowerPC (using PowerUP)
  72.     - output of any size 256 and 65536 colour chunky on ALL
  73.       systems
  74.     - resizeable window on (named/default) pubscreen or
  75.       256/65536 colour screen
  76.     - support for OCS, ECS, AGA, CyberGraphX 3+ and Picasso96
  77.     - double buffering on screen mode, if supported by gfxsystem
  78.     - DirectDraw with CyberGraphX 3+ and Picasso96
  79.     - uses features of AmigaOS 3.1 if available
  80.     - fast 0x0 optimized scale and remap routines, C versions for
  81.       PowerPC
  82.     - fast 040/060 tuned c2p for native modes (by Tim "Azure" Boescke),
  83.       C version for PowerPC
  84.     - support for cgxvideo.library for 16bit chunky in window mode
  85.     - optional native 12bit ham6 screen mode for 16bit chunky in
  86.       screen mode
  87.     - support for fblit, uses fastmem bitmaps when possible
  88.     - detects WCP/WPA8 patches and Akiko
  89.     - provides window IDCMP hook for user interaction
  90.     - user can switch between window and screen on the fly
  91.     - user can change screenmodes on the fly
  92.     - possible to skip rendering while window is inactive
  93.     - simple way to read commandline arguments / icon tooltypes
  94.       (also handles awin settings)
  95.     - can load xpk packed files with awloadfile (I had some spare
  96.       time:)
  97.     - all-in-one solution, no need to have extra files (drivers,
  98.       libraries etc.) so it can be used with intros too, and no
  99.       configuration problems as always autodetects best mode :)
  100.     - is free and comes with full source. see legal part.
  101.  
  102.    LEGAL
  103.     - awin package is written by Harry "Piru" Sintonen, except
  104.       cpu5azure2.ASM and ddazure2.ASM which are written by Tim
  105.       "Azure" Boescke. Used, modified and included here with his
  106.       permission. (thanks a lot mate)
  107.     - original awin is copyright (C) 1998-1999 Harry "Piru" Sintonen
  108.     - awin package is freeware. You can use it in your products,
  109.       even commercial ones.
  110.     - this source package is freely reuseable as long as original
  111.       documentation is preserved and credits are given properly.
  112.       ie. you can modify it for your purposes, but please credit
  113.       the original authors. Source distributions should have full
  114.       original source and documentation included.
  115.     - binary only distributions don't need to have original source
  116.       or documentation included, mentioning awin and authors in
  117.       program/game documentation or demo/intro readme is enough.
  118.     - If you modify awin only slightly and will release this new
  119.       version, please try to keep it compatible ie. don't modify
  120.       the API much. You can, of course, add new stuff to API (new
  121.       flags/args/tooltypes/chunky depths/functions etc).
  122.     - if modified versions should be released in public (ie.
  123.       Aminet), modified versions should have same legal status.
  124.       Also if your version differs from original quite a lot it is
  125.       suggested to have special suffix (your initials for example)
  126.       appended to awin name. anyways, awin and deriviates should
  127.       stay free.
  128.  
  129.    THANKS
  130.     #amiga - for being a pc channel <g>
  131.     #amigafin - for late night sessions
  132.     #amycoders - Azure, ChP-PwL, Duken, Kalsu, Kalms, Thain, Asa,
  133.                  Crisp + rest
  134.     #amigaquake - for refreshing fragfests
  135.  
  136.     Special thanks to Azure who generously gave me lots of sources
  137.     and guidance.. and pushed me the right way. Also thanks to all
  138.     guys who tested awin on various systems.
  139.  
  140.    OVERVIEW
  141.     This document is supposed to be a easy to use reference to
  142.     public awin functions. Also see awin.h and example code for
  143.     more information.
  144.  
  145. awin.o/awcreatedisplay                                 awin.o/awcreatedisplay
  146.  
  147.    NAME
  148.     awcreatedisplay - allocate awdisplay structure
  149.  
  150.    SYNOPSIS
  151.     awcreatedisplay()
  152.  
  153.     struct awdisplay *awcreatedisplay(void);
  154.  
  155.    FUNCTION
  156.     Allocate awdisplay structure. This call will allocate
  157.     memory for structure and open up some libraries and
  158.     devices.
  159.  
  160.    NOTE
  161.     This is the ONLY way to allocate this structure.
  162.     Use awdeletedisplay to free awdisplay structure.
  163.  
  164.    EXAMPLE
  165.         struct awdisplay *display;
  166.  
  167.         /* Allocate awdisplay structure */
  168.         display=awcreatedisplay();
  169.  
  170.    RESULTS
  171.     pointer to a awdisplay structure allocated or NULL
  172.     if no memory, SetPatch or Kickstart 3.0+.
  173.  
  174.    SEE ALSO
  175.     awdeletedisplay, awopendisplay
  176.  
  177. awin.o/awdeletedisplay                                 awin.o/awdeletedisplay
  178.  
  179.    NAME
  180.     awdeletedisplay - free awdisplay structure
  181.  
  182.    SYNOPSIS
  183.     awdeletedisplay(display)
  184.  
  185.     void awdeletedisplay(struct awdisplay *);
  186.  
  187.    FUNCTION
  188.     Free awdisplay structure. This call will free resources and
  189.     memory by structure.
  190.  
  191.    NOTE
  192.     This is the ONLY way to free this structure.
  193.     If display is open it will be closed before.
  194.  
  195.    EXAMPLE
  196.         /* free awdisplay structure */
  197.         awdeletedisplay(display);
  198.  
  199.    SEE ALSO
  200.     awcreatedisplay, awopendisplay, awclosedisplay
  201.  
  202. awin.o/awsetdebuglevel                                 awin.o/awsetdebuglevel
  203.  
  204.    NAME
  205.     awsetdebuglevel - set debug output verbosity level
  206.  
  207.    SYNOPSIS
  208.     awsetdebuglevel(display,level)
  209.  
  210.     ULONG awsetdebuglevel(struct awdisplay *,UBYTE);
  211.  
  212.    FUNCTION
  213.     Set debug verbosity level of display. Display must have been
  214.     created by awcreatedisplay call.
  215.  
  216.    NOTE
  217.     If awcreatedisplay fails it will always print debug output.
  218.  
  219.    EXAMPLE
  220.         /* Set debug output to normal */
  221.         awsetdebuglevel(display,AWD_VERBOSE);
  222.  
  223.         /* Supress debug output */
  224.         awsetdebuglevel(display,AWD_QUIET);
  225.  
  226.    INPUTS
  227.     display - pointer to a awdisplay structure allocated by
  228.           awcreatedisplay call.
  229.     level   - debug level, one of:
  230.               AWD_QUIET   - no debug output at all
  231.               AWD_VERBOSE - normal debug output
  232.               AWD_DEBUG   - full debug output
  233.  
  234.    RESULTS
  235.     returns old debug level, initially AWD_QUIET.
  236.  
  237.    SEE ALSO
  238.     awcreatedisplay
  239.  
  240. awin.o/awreadargs                                      awin.o/awreadargs
  241.  
  242.    NAME
  243.     awreadargs - handle commandline/tooltype arguments
  244.  
  245.    SYNOPSIS
  246.     awreadargs(display,odargs,template,array)
  247.  
  248.     struct awrdargs *awreadargs(struct awdisplay *,
  249.         struct awodargs *,const char *, LONG *);
  250.  
  251.    FUNCTION
  252.     Will parse awin settings to awodargs structure and
  253.     given template to array (like dos/ReadArgs). Also
  254.     translates icon tooltypes if program is started
  255.     from Workbench.
  256.  
  257.    NOTE
  258.     You MUST free awrdargs stucture with awfreeargs()!
  259.     array is valid ONLY till awfreeargs().
  260.  
  261.     Internal arguments are:
  262.  
  263.     WINDOW/S    - initially open as a window
  264.     SCREEN/S    - initially open as a screen
  265.     SCREENMODE8=MODEID8=MODEID/K
  266.             - 8bit screen mode modeid
  267.     SCREENMODE16=MODEID16/K
  268.             - 16bit screen mode modeid
  269.     REQUESTMODE8=REQMODE8=MODEREQ8/S
  270.             - open up screenmode request
  271.               for 8bit screen mode modeid
  272.     REQUESTMODE16=REQMODE16=MODEREQ16/S
  273.             - open up screenmode request
  274.               for 16bit screen mode modeid
  275.     PUBSCREEN=PUB/K    - name of the pubscreen to open
  276.               window mode window to.
  277.     WIDTH=WID=W/N/K    - initial display width
  278.     HEIGHT=HEI=H/N/K
  279.             - initial display height
  280.     UPDATEINACTIVE=UINA/T
  281.             - if display should update while
  282.               inactive
  283.     DOUBLEBUFFER=DBUFFER/T
  284.             - if awin should doublebuffer. this
  285.               slows down awin a bit, but looks
  286.               better
  287.     WAITSWAP/T    - if awin doublebuffer should
  288.               wait for swap. this usually
  289.               means max Hz/2. (25Hz for pal,
  290.               30Hz for ntsc)
  291.     FORCENATIVE=NATIVE/T
  292.             - if awin should force native mode,
  293.               even if user has gfxcard
  294.     USEHAM=HAM/T    - if awin should use HAM for
  295.               16bit screen mode on native
  296.               systems
  297.     DIRECTDRAW/T    - if CGFX3+ compatible directdraw
  298.               should be used
  299.     USECGXVIDEO=CGXV/T
  300.             - if cgxvideo.library vlayer should
  301.               be used for 16bit window mode
  302.     USEARGB16/T    - use 32bit ARGB truecolour for
  303.               better depth 16 output. normally
  304.               window and non-directdraw screen
  305.               mode convert depth 16 rgb to 256
  306.               colour. Note that USEARGB16 mode
  307.               is quite slow.
  308.  
  309.     See awopendisplay autodoc and awin.h for awodargs
  310.     structure defination.
  311.  
  312.    EXAMPLE
  313.         struct awodargs odargs;
  314.         struct awrdargs *rdargs;
  315.         LONG array[1];
  316.  
  317.         /* clear all (IMPORTANT!) */
  318.         memset(&odargs,0,sizeof(odargs));
  319.  
  320.         /* set defaults: */
  321.  
  322.         /* open as window, use directdraw if possible,
  323.            use absolute window positioning: */
  324.         odargs.flags=AWODAF_INITWINDOW|AWODAF_DIRECTDRAW|AWODAF_ABSPOS;
  325.         odargs.x=40; /* open window */
  326.         odargs.y=20; /* at this pos */
  327.  
  328.         /* translate internal arguments to odargs and
  329.            TEST/S to array */
  330.  
  331.         rdargs=awreadargs(display,&odargs,"TEST/S",array);
  332.         if (rdargs) {
  333.  
  334.           /* now odargs is filled with user chosen awin
  335.              settings and it can be used with
  336.              awcreatedisplay. array[0] is true if TEST is
  337.              specified on commandline/tooltypes (as you
  338.              would expect). */
  339.  
  340.           /* ... */
  341.  
  342.           awfreeargs(rdargs);
  343.         }
  344.  
  345.    INPUTS
  346.     display  - pointer to a awdisplay structure allocated by
  347.            awcreatedisplay call.
  348.     odargs   - pointer to awodargs structure. This structure
  349.            can (should) be initialized with default values.
  350.     template - formatting string as in dos/ReadArgs
  351.     array    - array of longwords for results, 1 per template entry
  352.  
  353.    RESULTS
  354.     pointer to a awrdargs structure allocated or NULL
  355.     if no memory, or bad arguments. If you get NULL you can use
  356.     IoErr() to find out reason for the problem. You MUST free this
  357.     structure with awfreeargs call. Do NOT make any assumptations
  358.     about contents of this structure.
  359.  
  360.    BUGS
  361.     In 1.0.12 release odargs flags could not be cleared by
  362.     awreadargs. Fixed in 1.0.13.
  363.  
  364.    SEE ALSO
  365.     awin.h/struct awodargs, awfreeargs, awopendisplay,
  366.     dos.library/ReadArgs
  367.  
  368. awin.o/awfreeargs                                      awin.o/awfreeargs
  369.  
  370.    NAME
  371.     awfreeargs - free commandline arguments
  372.  
  373.    SYNOPSIS
  374.     awfreeargs(args)
  375.  
  376.     void awfreeargs(struct awrdargs *);
  377.  
  378.    FUNCTION
  379.     Will free awrdargs structure allocated by awreadargs.
  380.  
  381.    EXAMPLE
  382.         awreadargs(rdargs);
  383.  
  384.    INPUTS
  385.     display  - pointer to a awdisplay structure allocated by
  386.            awcreatedisplay call.
  387.     odargs   - pointer to awodargs structure. This structure
  388.            can (should) be initialized with default values.
  389.     template - formatting string as in dos/ReadArgs
  390.     array    - array of longwords for results, 1 per template entry
  391.  
  392.    SEE ALSO
  393.     awreadargs, awopendisplay, dos.library/FreeArgs
  394.  
  395. awin.o/awcreatetimer                                   awin.o/awcreatetimer
  396.  
  397.    NAME
  398.     awcreatetimer - create a timer
  399.  
  400.    SYNOPSIS
  401.     awcreatetimer(display)
  402.  
  403.     struct awtimer *awcreatetimer(struct awdisplay *);
  404.  
  405.    FUNCTION
  406.     Allocates and starts a timer.
  407.  
  408.    NOTE
  409.     Actually awin timer system does not use timers but
  410.     timer.device/ReadEClock. PowerPC version uses PowerUP
  411.     kernel timer routines, so there always should be
  412.     minimum overhead calling these timer routines. You
  413.     can allocate as many timers as you need. Do NOT make
  414.     any assumptations about contents of awtimer structure.
  415.  
  416.    EXAMPLE
  417.         struct awtimer *timer;
  418.  
  419.         timer=awalloctimer(display);
  420.         if (timer) {
  421.  
  422.           /* now timer is ready for use */
  423.  
  424.  
  425.           awdeletetimer(timer);
  426.         }
  427.  
  428.    INPUTS
  429.     display  - pointer to a awdisplay structure allocated by
  430.            awcreatedisplay call.
  431.  
  432.    RESULTS
  433.     pointer to a awtimer structure allocated or NULL
  434.     if no memory.
  435.  
  436.    SEE ALSO
  437.     awrestarttimer, awreadtimer, awreadtimer_us, awdeletetimer
  438.  
  439. awin.o/awrestarttimer                                  awin.o/awrestarttimer
  440.  
  441.    NAME
  442.     awrestarttimer - restart a timer
  443.  
  444.    SYNOPSIS
  445.     awrestarttimer(timer)
  446.  
  447.     void awrestarttimer(struct awtimer *);
  448.  
  449.    FUNCTION
  450.     Restarts a timer.
  451.  
  452.    EXAMPLE
  453.         awrestarttimer(timer);
  454.  
  455.    INPUTS
  456.     timer  - pointer to awtimer structure allocated by
  457.          awcreatetimer call.
  458.  
  459.    SEE ALSO
  460.     awcreatetimer, awreadtimer, awreadtimer_us, awdeletetimer
  461.  
  462. awin.o/awreadtimer                                     awin.o/awreadtimer
  463.  
  464.    NAME
  465.     awreadtimer - read current ticks
  466.  
  467.    SYNOPSIS
  468.     awreadtimer(timer)
  469.  
  470.     ULONG awreadtimer(struct awtimer *);
  471.  
  472.    FUNCTION
  473.     Return milliseconds elapsed since awcreatetimer/
  474.     awrestarttimer for this timer.
  475.  
  476.    EXAMPLE
  477.         ULONG ticks;
  478.         ticks=awreadtimer(timer);
  479.  
  480.    INPUTS
  481.     timer  - pointer to awtimer structure allocated by
  482.          awcreatetimer call.
  483.  
  484.    RESULTS
  485.     unsigned long of milliseconds elapsed.
  486.  
  487.    SEE ALSO
  488.     awcreatetimer, awrestarttimer, awreadtimer_us, awdeletetimer
  489.  
  490. awin.o/awreadtimer_us                                  awin.o/awreadtimer_us
  491.  
  492.    NAME
  493.     awreadtimer_us - read current ticks
  494.  
  495.    SYNOPSIS
  496.     awreadtimer_us(timer)
  497.  
  498.     ULONG awreadtimer_us(struct awtimer *);
  499.  
  500.    FUNCTION
  501.     Return microseconds elapsed since awcreatetimer/
  502.     awrestarttimer for this timer.
  503.  
  504.    EXAMPLE
  505.         ULONG ticks_us;
  506.         ticks_us=awreadtimer_us(timer);
  507.  
  508.    INPUTS
  509.     timer  - pointer to awtimer structure allocated by
  510.          awcreatetimer call.
  511.  
  512.    RESULTS
  513.     unsigned long of microseconds elapsed.
  514.  
  515.    SEE ALSO
  516.     awcreatetimer, awrestarttimer, awreadtimer, awdeletetimer
  517.  
  518. awin.o/awdeletetimer                                   awin.o/awdeletetimer
  519.  
  520.    NAME
  521.     awdeletetimer - delete a timer
  522.  
  523.    SYNOPSIS
  524.     awdeletetimer(timer)
  525.  
  526.     void awdeletetimer(struct awtimer *);
  527.  
  528.    FUNCTION
  529.     Free resources bound to this timer.
  530.  
  531.    EXAMPLE
  532.         awdeletetimer(timer);
  533.  
  534.    INPUTS
  535.     timer  - pointer to awtimer structure allocated by
  536.          awcreatetimer call.
  537.  
  538.    SEE ALSO
  539.     awcreatetimer, awrestarttimer, awreadtimer, awreadtimer_us
  540.  
  541. awin.o/awsetidcmphook                                  awin.o/awsetidcmphook
  542.  
  543.    NAME
  544.     awsetidcmphook - set a display IDCMP hook
  545.  
  546.    SYNOPSIS
  547.     awsetidcmphook(display,idcmphook)
  548.  
  549.     AWIDCMPHOOK_PTR awsetidcmphook(struct awdisplay *,
  550.         AWIDCMPHOOK_PTR);
  551.  
  552.    FUNCTION
  553.     Set display IDCMP callback function.
  554.  
  555.    NOTE
  556.     Note that function does NOT take in/return AmigaOS
  557.     hook structure, but *function pointer*.
  558.  
  559.     For now idcmphook should always return AWIDHA_NOP.
  560.  
  561.    EXAMPLE
  562.         ULONG myhook(struct IntuiMessage *imsg) {
  563.           /* imsg is copy of replied IDCMP intuimessage */
  564.           return AWIDHA_NOP;
  565.         }
  566.  
  567.         /* will call myhook for IDMCP_VANILLAKEY */
  568.         awsetidcmphook(display,myhook);
  569.         awsetidcmpflags(display,IDMCP_VANILLAKEY);
  570.  
  571.    INPUTS
  572.     display   - pointer to a awdisplay structure allocated by
  573.             awcreatedisplay call.
  574.     idcmphook - pointer to function returning ULONG and
  575.                 taking in struct IntuiMessage *.
  576.  
  577.         idcmphook prototype is:
  578.         ULONG myhook(struct IntuiMessage *);
  579.  
  580.         That is you get pointer to IntuiMessage in,
  581.         and you return ULONG.
  582.  
  583.         You get a local copy of replied IntuiMessage
  584.         from awin window, this same copy is later used
  585.         to handle internal events. So you may also use
  586.         hook to filter out some or all user input. This
  587.         is not recommended (it's a bit rude to ignore
  588.         user input), but possible.
  589.  
  590.         For example to use hook to disable keyboard
  591.         interaction you would do:
  592.  
  593.         ULONG myhook(struct IntuiMessage *imsg) {
  594.  
  595.           /* you can handle your own stuff here
  596.              .... */
  597.  
  598.           /* test not really needed it this case, but if you
  599.              add idcmpflags to awsetidcmpflags() then it IS. */
  600.  
  601.           if ( (imsg->Class==IDCMP_RAWKEY) ||
  602.                (imsg->Class==IDCMP_VANILLAKEY) ) {
  603.             imsg->Class=0;
  604.           }
  605.           return AWIDHA_NOP;
  606.         }
  607.  
  608.         awsetidcmphook(display,myhook);
  609.         awsetidcmpflags(display,IDCMP_RAWKEY|IDMCP_VANILLAKEY);
  610.  
  611.    RESULTS
  612.     pointer to old idcmphook (initially NULL).
  613.  
  614.    BUGS
  615.     Your hook doesn't get IDCMP_RAWKEY key releases.
  616.     If you need accurate input use input handler.
  617.  
  618.    SEE ALSO
  619.     awsetidcmpflags, awhandleinput
  620.  
  621. awin.o/awsetidcmpflags                                 awin.o/awsetidcmpflags
  622.  
  623.    NAME
  624.     awsetidcmpflags - set a display IDCMP hook flags
  625.  
  626.    SYNOPSIS
  627.     awsetidcmpflags(display,idcmpflags)
  628.  
  629.     ULONG awsetidcmpflags(struct awdisplay *,
  630.         ULONG);
  631.  
  632.    FUNCTION
  633.     Set display IDCMP callback function flags.
  634.  
  635.    NOTE
  636.     Does ModifyIDCMP window if it is required to get
  637.     intuition send these IDCMP messages.
  638.  
  639.    EXAMPLE
  640.         ULONG oldflags;
  641.  
  642.         oldflags=awsetidcmpflags(display,IDMCP_VANILLAKEY);
  643.  
  644.    INPUTS
  645.     display    - pointer to a awdisplay structure allocated by
  646.              awcreatedisplay call.
  647.     idcmpflags - mask of flags display IDCMP hook is called with.
  648.  
  649.    RESULTS
  650.     ULONG of old idcmpflags (initially 0).
  651.  
  652.    SEE ALSO
  653.     awsetidcmphook, awhandleinput
  654.  
  655. awin.o/awinitchunkystruct                              awin.o/awinitchunkystruct
  656.  
  657.    NAME
  658.     awinitchunkystruct - allocate awchunky structure for width,
  659.                 height and depth
  660.  
  661.    SYNOPSIS
  662.     awinitchunkystruct(display,width,height,depth)
  663.  
  664.     struct awchunky *awinitchunkystruct(struct awdisplay *,
  665.         ULONG,ULONG,ULONG);
  666.  
  667.    FUNCTION
  668.     Allocates awchunky structure and initializes width,
  669.     height and depth to given values. This is useful if you
  670.     have your own framebuffer for chunky.
  671.  
  672.    NOTE
  673.     You MUST set framebuffer pointer before use! Do NOT
  674.     set `memory' of awchunky structure yourself!
  675.  
  676.     You should make sure your framebuffer is properly
  677.     aligned (speed issues, 68k<->ppc cache issues).
  678.     Aligning with 32 bytes should be always enough.
  679.  
  680.     You should always use awallocchunky. :)
  681.  
  682.    EXAMPLE
  683.         /* how to use your custom framebuffer mydata */
  684.  
  685.         struct awchunky *chunky;
  686.  
  687.         chunky=awinitchunkystruct(display,320,200,8);
  688.         if (chunky) {
  689.           chunky->framebuffer=(UBYTE *)mydata;
  690.  
  691.           /* will NOT try to free mydata */
  692.           awfreechunky(chunky);
  693.         }
  694.  
  695.    INPUTS
  696.     display  - pointer to a awdisplay structure allocated by
  697.            awcreatedisplay call.
  698.     width    - width of chunky framebuffer (will be ceiled to
  699.            multiple of 32)
  700.     height   - height of chunky framebuffer
  701.     depth     - depth of framebuffer:
  702.              8 - LUT8
  703.             16 - RGB565
  704.  
  705.    RESULTS
  706.     pointer to awchunky structure or NULL.
  707.  
  708.    BUGS
  709.     CGFX/P96 depth 16 directdraw did not work in 1.0.12 release
  710.     due stupid bug. Fixed in 1.0.13.
  711.  
  712.    SEE ALSO
  713.     awallocchunky, awfreechunky
  714.  
  715. awin.o/awallocchunky                                   awin.o/awallocchunky
  716.  
  717.    NAME
  718.     awallocchunky - allocate awchunky structure and framebuffer
  719.             for width, height and depth
  720.  
  721.    SYNOPSIS
  722.     awallocchunky(display,width,height,depth)
  723.  
  724.     struct awchunky *awallocchunky(struct awdisplay *,
  725.         ULONG,ULONG,ULONG);
  726.  
  727.    FUNCTION
  728.     Allocates awchunky structure and framebuffer according to
  729.     given width, height and depth.
  730.  
  731.    EXAMPLE
  732.         struct awchunky *chunky;
  733.  
  734.         chunky=awinitchunkystruct(display,320,240,8);
  735.  
  736.    INPUTS
  737.     display  - pointer to a awdisplay structure allocated by
  738.            awcreatedisplay call.
  739.     width    - width of chunky framebuffer (will be ceiled to
  740.            multiple of 32)
  741.     height   - height of chunky framebuffer
  742.     depth     - depth of framebuffer:
  743.              8 - LUT8
  744.             16 - RGB565
  745.  
  746.    RESULTS
  747.     pointer to awchunky structure or NULL.
  748.  
  749.    BUGS
  750.     CGFX/P96 depth 16 directdraw did not work in 1.0.12 release
  751.     due stupid bug. Fixed in 1.0.13.
  752.  
  753.    SEE ALSO
  754.     awinitchunkystruct, awfreechunky
  755.  
  756. awin.o/awfreechunky                                    awin.o/awfreechunky
  757.  
  758.    NAME
  759.     awfreechunky - free awchunky structure (and framebuffer memory)
  760.  
  761.    SYNOPSIS
  762.     awfreechunky(chunky)
  763.  
  764.     void awfreechunky(struct awchunky *);
  765.  
  766.    FUNCTION
  767.     Free awchunky structure and framebuffer associated to it.
  768.  
  769.    NOTE
  770.     Will only free framebuffer if it was allocated by
  771.     awallocchunky.
  772.  
  773.    INPUTS
  774.     chunky  - pointer to a awchunky structure allocated by
  775.           awinitchunkystruct or awallocchunky call.
  776.  
  777.    SEE ALSO
  778.     awinitchunkystruct, awallocchunky
  779.  
  780. awin.o/awopendisplay                                   awin.o/awopendisplay
  781.  
  782.    NAME
  783.     awopendisplay - open display (window or screen)
  784.  
  785.    SYNOPSIS
  786.     awopendisplay(display,odargs)
  787.  
  788.     ULONG awopendisplay(struct awdisplay *,
  789.         struct awodargs *);
  790.  
  791.    FUNCTION
  792.     Open display (window or screen). Actually the display
  793.     opens on first awrenderchunky or awrenderchunky_show
  794.     call.
  795.  
  796.    NOTE
  797.     odargs should have been called with awreadargs. See
  798.     autodoc of awreadargs.
  799.  
  800.     See awin.h for awodargs structure defination.
  801.  
  802.    INPUTS
  803.     display  - pointer to a awdisplay structure allocated by
  804.            awcreatedisplay call.
  805.     odargs   - opendisplayarguments possibly modified by
  806.            awreadargs call
  807.  
  808.     odargs structure has following fields:
  809.  
  810.         flags - contains flags that tell awin how to handle
  811.             this display. See awin.h AWODAF_ flags.
  812.         modeid8 - screenmode to use for 8bit modes, 0 for
  813.             BestModeID.
  814.         modeid16 - screenmode to use for 16bit modes, 0 for
  815.             BestModeID.
  816.         witdh - initial display width.
  817.         height - initial display height.
  818.         x, y - displacement to visible screen center, OR abs
  819.             left&top if AWODAF_ABSPOS.
  820.         title - pointer to window title string.
  821.         pubscreen - pointer to pubscreen to open window to.
  822.         unused0 - this should be NULL for now.
  823.  
  824.         For more information, see awin.h
  825.  
  826.    RESULTS
  827.     success indicator
  828.  
  829.    SEE ALSO
  830.     awin.h/struct awodargs, awclosedisplay, awhandleinput,
  831.     awrenderchunky
  832.  
  833. awin.o/awclosedisplay                                  awin.o/awclosedisplay
  834.  
  835.    NAME
  836.     awclosedisplay - close display (window or screen)
  837.  
  838.    SYNOPSIS
  839.     awclosedisplay(display)
  840.  
  841.     void awclosedisplay(struct awdisplay *);
  842.  
  843.    FUNCTION
  844.     Close awdisplay window or screen unless already
  845.     closed.
  846.  
  847.    INPUTS
  848.     display  - pointer to a awdisplay structure allocated by
  849.            awcreatedisplay call.
  850.  
  851.    SEE ALSO
  852.     awopendisplay, awhandleinput, awrenderchunky
  853.  
  854. awin.o/awsetpalette                                    awin.o/awsetpalette
  855.  
  856.    NAME
  857.     awsetpalette - set display LUT8 palette
  858.  
  859.    SYNOPSIS
  860.     awsetpalette(display,palette,num)
  861.  
  862.     ULONG awsetpalette(struct awdisplay *,ULONG *,ULONG);
  863.  
  864.    FUNCTION
  865.     Set display LUT8 palette.
  866.  
  867.    NOTE
  868.     display need not be open. Do NOT call this function
  869.     often, unless in screen mode (!display->windowmode).
  870.     In window mode this function forces remap to screen
  871.     palette and this takes some time.
  872.  
  873.     You MUST awsetpalette at least once before you render
  874.     LUT8 chunky.
  875.  
  876.    INPUTS
  877.     display  - pointer to a awdisplay structure allocated by
  878.            awcreatedisplay call.
  879.     palette  - array of 00RRGGBB unsigned longs.
  880.     num      - number of entries in palettearray, min 1,
  881.            max 256
  882.  
  883.    RESULTS
  884.     success indicator (generally this can only fail if you
  885.     give wrong num)
  886.  
  887.    SEE ALSO
  888.     awrenderchunky
  889.  
  890. awin.o/awhandleinput                                   awin.o/awhandleinput
  891.  
  892.    NAME
  893.     awhandleinput - handle IDCMP messages
  894.  
  895.    SYNOPSIS
  896.     awhandleinput(display)
  897.  
  898.     ULONG awhandleinput(struct awdisplay *);
  899.  
  900.    FUNCTION
  901.     Handle IDCMP messages. Will call idcmphook if set.
  902.  
  903.    NOTE
  904.     This call handles internal input and program set IDCMP
  905.     hook. This function can take minutes to return (user can
  906.     play with screenmoderequester). You should call this
  907.     function often (~4 times per second is ok). If you need
  908.     to get more precise user input call it more often (10-20
  909.     timer per second). Note that PowerUP version slows down
  910.     if you call this function too often.
  911.  
  912.     If you need very accurate user input use a input handler
  913.     (see input.device/IND_ADDHANDLER). You should call
  914.     awhandleinput anyways though. Supporting PPC and
  915.     inputhandler is a bit tricky (you probably need to write
  916.     it in 68k pc relative asm and include it into c program
  917.     and then allocate memory for it + copy it there + set
  918.     pointer to your 68k<->ppc bridge memory into it. then
  919.     install that routine as inputhandler. note that your
  920.     bridgemem should probably be allocated with
  921.     MEMF_NOCACHEPPC|MEMF_NOCACHEM68K).
  922.  
  923.     There are some internal keys defined for awin (these
  924.     can be overridden/remapped with idcmphook if needed):
  925.  
  926.     ESC, Q  - quit
  927.     W       - goto window mode
  928.     S       - goto screen mode
  929.     TAB     - toggle window/screen mode
  930.     P       - pause rendering
  931.     SPACE   - reset window size
  932.     M       - change screen mode ModeID and size, also
  933.               affects window size.
  934.  
  935.    INPUTS
  936.     display  - pointer to a awdisplay structure allocated by
  937.            awcreatedisplay call.
  938.  
  939.    RESULTS
  940.     Will return 0 if program should quit, else >0. If you have
  941.     multiple awhandleidcmp loops on quit condition you must skip
  942.     rest of the loops (or else user gets a bit confused).
  943.  
  944.    SEE ALSO
  945.     awrenderchunky, input.device/IND_ADDHANDLER
  946.  
  947. awin.o/awrenderchunky                                  awin.o/awrenderchunky
  948.  
  949.    NAME
  950.     awrenderchunky - render chunky to display
  951.  
  952.    SYNOPSIS
  953.     awrenderchunky(display,chunky)
  954.  
  955.     awrenderchunky(struct awdisplay *,
  956.         struct awchunky *);
  957.  
  958.    FUNCTION
  959.     Render given chunky to display as fast as possible.
  960.  
  961.    NOTE
  962.     If you render 16bit chunky display will close and reopen
  963.     in 16bit mode (screen will physically close/open only if
  964.     `real' 16bit mode is available). Then if you render 8bit
  965.     chunky display will reopen in 8bit mode again.
  966.  
  967.    INPUTS
  968.     display  - pointer to a awdisplay structure allocated by
  969.            awcreatedisplay call.
  970.     chunky   - pointer to a awchunky structure allocated by
  971.            awinitchunkystruct or awallocchunky call.
  972.  
  973.    SEE ALSO
  974.     awopendisplay, awallocchunky, awhandleinput, awrenderchunky_show
  975.  
  976. awin.o/awrenderchunky_show                             awin.o/awrenderchunky_show
  977.  
  978.    NAME
  979.     awrenderchunky - render chunky to display and make it visible
  980.  
  981.    SYNOPSIS
  982.     awrenderchunky_show(display,chunky)
  983.  
  984.     awrenderchunky_show(struct awdisplay *,
  985.         struct awchunky *);
  986.  
  987.    FUNCTION
  988.     Render given chunky to display and force display visible.
  989.  
  990.     This function can be used to display still pictures,
  991.     regardless of double (or possible future triple) buffering
  992.     or other factors.
  993.  
  994.    NOTE
  995.     If you render 16bit chunky display will close and reopen
  996.     in 16bit mode (screen will physically close/open only if
  997.     `real' 16bit mode is available). Then if you render 8bit
  998.     chunky display will reopen in 8bit mode again.
  999.  
  1000.    INPUTS
  1001.     display  - pointer to a awdisplay structure allocated by
  1002.            awcreatedisplay call.
  1003.     chunky   - pointer to a awchunky structure allocated by
  1004.            awinitchunkystruct or awallocchunky call.
  1005.  
  1006.    BUGS
  1007.     If user resizes window or changes screenmode while still
  1008.     picture is being viewed it will be destroyed. So you're
  1009.     adviced to code still picture viewer to call awrenderchunky
  1010.     & awhandleinput in loop instead.
  1011.  
  1012.    SEE ALSO
  1013.     awopendisplay, awallocchunky, awhandleinput, awrenderchunky
  1014.  
  1015. awin.o/awloadfile                                      awin.o/awloadfile
  1016.  
  1017.    NAME
  1018.     awloadfile - load a file
  1019.  
  1020.    SYNOPSIS
  1021.     awloadfile(name)
  1022.  
  1023.     struct awfile *awloadfile(const char *);
  1024.  
  1025.    FUNCTION
  1026.     Allocate memory for awfile structure and file.
  1027.     Read the file.
  1028.  
  1029.    NOTE
  1030.     awfile->size will contain filesize.
  1031.     awfile->data will point to loaded data.
  1032.     Other fields are private!
  1033.  
  1034.     Supports XPK packed files with xpkmaster.library.
  1035.  
  1036.    INPUTS
  1037.     name  - pointer to file path
  1038.  
  1039.    RESULTS
  1040.     pointer to awfile structure or NULL (file not found or
  1041.     no memory).
  1042.  
  1043.    SEE ALSO
  1044.     awfreefile
  1045.  
  1046. awin.o/awfreefile                                      awin.o/awfreefile
  1047.  
  1048.    NAME
  1049.     awfreefile - free awloadfile file
  1050.  
  1051.    SYNOPSIS
  1052.     awfreefile(file)
  1053.  
  1054.     void awfreefile(struct awfile *);
  1055.  
  1056.    FUNCTION
  1057.     Free memory associated to awfile structure.
  1058.  
  1059.    INPUTS
  1060.     file  - pointer to awfile structure to free
  1061.  
  1062.    SEE ALSO
  1063.     awreadfile
  1064.  
  1065.